home *** CD-ROM | disk | FTP | other *** search
/ Aminet 12 / Aminet 12 (1996)(GTI - Schatztruhe)[!][Jun 1996].iso / Aminet / dev / misc / BST_SystemDocs.lha / BeastV1 / Source / BST_System / BeastLibrary.doc next >
Encoding:
Text File  |  1996-03-31  |  16.6 KB  |  647 lines
  1. TABLE OF CONTENTS
  2.  
  3. BST_System/BeastLibrary
  4. BeastLibrary/BST_AddClass
  5. BeastLibrary/BST_ApplyTagChanges
  6. BeastLibrary/BST_CloneTagItems
  7. BeastLibrary/BST_FindTagItem
  8. BeastLibrary/BST_FreeClass
  9. BeastLibrary/BST_FreeTagItems
  10. BeastLibrary/BST_MakeClass
  11. BeastLibrary/BST_MakeSubClass
  12. BeastLibrary/BST_NextTagItem
  13. BeastLibrary/BST_RemoveClass
  14. BeastLibrary/CLSS_AddMethod
  15. BeastLibrary/CLSS_DisposeMethod
  16. BeastLibrary/CLSS_FindMethod
  17. BeastLibrary/OBJ_CreateConnection
  18. BeastLibrary/OBJ_DestroyObject
  19. BeastLibrary/OBJ_DisposeObject
  20. BeastLibrary/OBJ_DoMethod
  21. BeastLibrary/OBJ_FromInput
  22. BeastLibrary/OBJ_MethodToChildren
  23. BeastLibrary/OBJ_MethodToParent
  24. BeastLibrary/OBJ_NewObject
  25. BeastLibrary/OBJ_RemoveConnection
  26. BeastLibrary/OBJ_ToOutput
  27. BST_System/BeastLibrary
  28.  
  29.   NAME
  30.     BeastLibrary -- Library for BEAST. (V1 Alpha)
  31.  
  32.   COPYRIGHT
  33.     Maverick Software Development
  34.  
  35.   FUNCTION
  36.     The BEAST engine.
  37.  
  38.   AUTHOR
  39.     Jacco van Weert
  40.  
  41.   CREATION DATE
  42.     23-Apr-95
  43.  
  44.   MODIFICATION HISTORY
  45.     27-Mar-96:    First release, V1 Alpha.
  46.  
  47.   NOTES
  48.  
  49.  
  50. BeastLibrary/BST_AddClass
  51.  
  52.   NAME
  53.     BST_AddClass -- Add a Beast class to the class list. (V1 Alpha)
  54.  
  55.   SYNOPSIS
  56.     AddClass( Class )
  57.               A0
  58.     void BST_AddClass( struct BST_Class * );
  59.  
  60.   FUNCTION
  61.     Add the Beast class to the Beast system.
  62.  
  63.   INPUTS
  64.     Class - Pointer to the class.
  65.  
  66.   SEE ALSO
  67.     BST_RemoveClass, BST_MakeClass
  68.  
  69.  
  70. BeastLibrary/BST_ApplyTagChanges
  71.  
  72.   NAME
  73.     BST_ApplyTagChanges -- (V1 Alpha)
  74.  
  75.   SYNOPSIS
  76.     BST_ApplyTagChanges( list, changeList )
  77.                          A0    A1
  78.  
  79.   FUNCTION
  80.     <Same as in the utility.library>
  81.  
  82.   NOTES
  83.     This routine is subject to change
  84.  
  85.  
  86. BeastLibrary/BST_CloneTagItems
  87.  
  88.   NAME
  89.     BST_CloneTagItems -- (V1 Alpha)
  90.  
  91.   SYNOPSIS
  92.     clone = BST_CloneTagItems( original )
  93.     D0                         A0
  94.  
  95.   FUNCTION
  96.     <Same as in the utility.library>
  97.  
  98.   NOTES
  99.     This routine is subject to change
  100.  
  101.  
  102. BeastLibrary/BST_FindTagItem
  103.  
  104.   NAME
  105.     BST_FindTagItem -- (V1 Alpha)
  106.  
  107.   SYNOPSIS
  108.     Result = BST_FindTagItem( tagValue, tagList )
  109.     D0,A0                     D0        A0
  110.     struct TagItem *BST_FindTagItem( ULONG, struct TagItem * );
  111.  
  112.   FUNCTION
  113.     Same functionallity as the utility.library equivalent, added are
  114.     special handling functions for the BEAST tags.
  115.  
  116.  
  117. BeastLibrary/BST_FreeClass
  118.  
  119.   NAME
  120.     BST_FreeClass -- Free a Beast class. (V1 Alpha)
  121.  
  122.   SYNOPSIS
  123.     BST_FreeClass( Class )
  124.                    A0
  125.     void BST_FreeClass( struct BST_Class );
  126.  
  127.   FUNCTION
  128.     Free the Beast class from the memory. Also deallocate all class related
  129.     stuff. Such as the methods lists.
  130.  
  131.   INPUTS
  132.     Class - Pointer to the class.
  133.  
  134.   NOTES
  135.     Before this routine BST_RemoveClass must be called.
  136.  
  137.   BUGS
  138.     No check if the Class is still in use.
  139.  
  140.   SEE ALSO
  141.     BST_RemoveClass, BST_MakeClass
  142.  
  143.  
  144. BeastLibrary/BST_FreeTagItems
  145.  
  146.   NAME
  147.     BST_FreeTagItems -- (V1 Alpha)
  148.  
  149.   SYNOPSIS
  150.     BST_FreeTagItems( taglist )
  151.                       A0
  152.  
  153.   FUNCTION
  154.     <Same as in the utility.library>
  155.  
  156.   NOTES
  157.     This routine is subject to change
  158.  
  159.  
  160. BeastLibrary/BST_MakeClass
  161.  
  162.   NAME
  163.     BST_MakeClass -- Make a Beast class. (V1 Alpha)
  164.  
  165.   SYNOPSIS
  166.     Result = BST_MakeClass( ClassID, InstanceSize )
  167.     D0                      A0       D0
  168.     struct BST_Class *BST_MakeClass( char *, ULONG );
  169.  
  170.   FUNCTION
  171.     Defines a new public class, BST_AddClass must be called to add
  172.     the class to the BEAST system.
  173.  
  174.   INPUTS
  175.     ClassID      - Class ID, pointer to the public-name.
  176.                    Please choose this name carefully, otherwise a
  177.                    conflict may occur.
  178.                    Beast classes always are starting with a 'B'.
  179.                    BST_,  BVS_, BFS_, ..etc..
  180.  
  181.     InstanceSize - The Instance size in bytes.
  182.  
  183.   RESULT
  184.     Result - The created class
  185.  
  186.   SEE ALSO
  187.     BST_FreeClass, BST_AddClass
  188.  
  189.  
  190. BeastLibrary/BST_MakeSubClass
  191.  
  192.   NAME
  193.     BST_MakeSubClass -- Make a Beast subclass. (V1 Alpha)
  194.  
  195.   SYNOPSIS
  196.     Result = BST_MakeSubClass( ClassID, InstanceSize, SuperClass )
  197.     D0                         A0       D0            A1
  198.  
  199.   FUNCTION
  200.     The same function as BST_MakeClass, only now this class is a subclass
  201.     of 'SuperClass'. This superclass _must_ be added to the system, because
  202.     at least 1 object is created of this class.
  203.  
  204.   INPUTS
  205.     ClassID      - Class ID, pointer to public-name.
  206.     InstanceSize - The private class datasize in bytes.
  207.     SuperClass   - The name of the SuperClass.
  208.  
  209.   RESULT
  210.     Result - The created sub class
  211.  
  212.   SEE ALSO
  213.     BST_FreeClass, BST_AddClass, BST_MakeClass
  214.  
  215.  
  216. BeastLibrary/BST_NextTagItem
  217.  
  218.   NAME
  219.     BST_NextTagItem -- (V1 Alpha)
  220.  
  221.   SYNOPSIS
  222.     Result = BST_NextTagItem( tagList )
  223.     D0,A0                     A0
  224.     struct TagItem *BST_NextTagItem( struct TagItem * );
  225.  
  226.   FUNCTION
  227.     Similar function as the one in the utility.library, only this
  228.     takes care about some BEAST tags.
  229.  
  230.   RESULT
  231.     Result - Pointer to the new position.
  232.              =NULL when end of TagList
  233.  
  234.  
  235. BeastLibrary/BST_RemoveClass
  236.  
  237.   NAME
  238.     BST_RemoveClass -- Remove a Beast class from the class list. (V1 Alpha)
  239.  
  240.   SYNOPSIS
  241.     BST_RemoveClass( Class )
  242.                      A0
  243.     void BST_RemoveClass( struct BST_Class * );
  244.  
  245.   FUNCTION
  246.     Unlink the Beast class from the list.
  247.  
  248.   INPUTS
  249.     Class - Pointer to the class.
  250.  
  251.   SEE ALSO
  252.     BST_AddClass, BST_FreeClass
  253.  
  254.  
  255. BeastLibrary/CLSS_AddMethod
  256.  
  257.   NAME
  258.     CLSS_AddMethod -- Add a Method to a class. (V1 Alpha)
  259.  
  260.   SYNOPSIS
  261.     Result = CLSS_AddMethod( Class, MethodStart, Method_ID )
  262.     D0                       A0     A1           D0
  263.     struct BST_Class CLSS_AddMethod( struct BST_Class *, ULONG *, BST_Method );
  264.  
  265.   FUNCTION
  266.     Add a method to a class, every method may have several method-routines.
  267.     The Beast system has a large number of pre-defined method ID's.
  268.     There are a number of free slots for local methods. Please consider
  269.     very carefully when using local methods ID. Those are not supported
  270.     among other classes. Also _NEVER_ use method delegation (MTHF_DOPARENTS,
  271.     MTHF_DOCHILDREN..etc..) when using local methods. In the BEAST OO system
  272.     objects are _never_ sure who parents or children are, even if you add them
  273.     yourself.
  274.     Free slots for local method ID's:
  275.           OBM_local0      =       0x00000040 - 0x0000007F
  276.           OBM_local1      =       0x00000100 - 0x000007FF
  277.           OBM_local2      =       0x00004000 - 0x00004FFF
  278.           OBM_local3      =       0x00100000 - 0x001FFFFF
  279.  
  280.     The method ID's with the lowest number have the highest priority. In
  281.     V1 Alpha the priority is not yet implemented, but it will be in the future.
  282.  
  283.   INPUTS
  284.     Class       - Pointer to the class.
  285.     MethodStart - The start of the method routine.
  286.     Method_ID   - The Method_ID number.
  287.  
  288.   RESULT
  289.     Result - =NULL when Error.
  290.              <>NULL Class.
  291.  
  292.   SEE ALSO
  293.     CLSS_DisposeMethod
  294.  
  295.  
  296. BeastLibrary/CLSS_DisposeMethod
  297.  
  298.   NAME
  299.     CLSS_DisposeMethod -- Dispose a Method from a class. (V1 Alpha)
  300.  
  301.   SYNOPSIS
  302.     CLSS_DisposeMethod( Class, MethodStart, Method_ID )
  303.                         A0     A1           D0
  304.     void CLSS_DisposeMethod( struct BST_Class *, ULONG *, BST_Method );
  305.  
  306.   FUNCTION
  307.     Remove the method from the class.
  308.  
  309.   INPUTS
  310.     Class       - Pointer to the class.
  311.     MethodStart - Start of the method routine.
  312.     Method_ID   - Method ID number
  313.  
  314.   SEE ALSO
  315.     CLSS_AddMethod
  316.  
  317.  
  318. BeastLibrary/CLSS_FindMethod
  319.  
  320.   NAME
  321.     CLSS_FindMethod -- Find a Method in a class. (V1 Alpha)
  322.  
  323.   SYNOPSIS
  324.     Result = CLSS_FindMethod( Class, Method_ID )
  325.     D0,A0                     A0     D0
  326.     struct class_MethodList *CLSS_FindMethod( struct BST_Class *, BST_Method );
  327.  
  328.   FUNCTION
  329.     Search for a certain method ID.
  330.  
  331.   INPUTS
  332.     Class     - Pointer to the class.
  333.     Method_ID - Method ID number.
  334.  
  335.   RESULT
  336.     Result - Pointer to found CLSS_MethodList or NULL when the method
  337.              is not found.
  338.  
  339.  
  340. BeastLibrary/OBJ_CreateConnection
  341.  
  342.   NAME
  343.     OBJ_CreateConnection -- Create a connection between two methods. (V1 Alpha)
  344.  
  345.   SYNOPSIS
  346.     Result = OBJ_CreateConnection( FromObject, ToObject, FromMethod, ToMethod )
  347.     D0                             A0          A1        D0          D1
  348.     struct obj_OutputLink *OBJ_CreateConnection( struct BST_Object *, struct BST_Object *, BST_Method, BST_Method );
  349.  
  350.   FUNCTION
  351.     Create a connection between two objects. Every Method can be connected to any
  352.     other method. Connections between objects running at the same task will be
  353.     a direct connection. When connecting to object of different task the routine
  354.     will insert an intermediair (not implemented in V1 Alpha). The same when connecting
  355.     between two objects at two different computer systems.
  356.     A connection can have multiple inputs and outputs. But a things must be take into
  357.     consideration. When a 'FromMethod' is connected to several other methods the
  358.     TagList (which is the data) is shared among the connected objects, which means
  359.     that if the first object changes something in the TagList, the others will also
  360.     see it.
  361.  
  362.   INPUTS
  363.     FromObject - Pointer to the 'From' object.
  364.     ToObject   - Pointer to the 'To' object
  365.     FromMethod - The Method ID number of the FromObject.
  366.     ToMethod   - The Method ID number of the ToObject.
  367.  
  368.   RESULT
  369.     Result - 0 = An error has occured. Also when FromObject or ToObject
  370.                  is zero. Otherwise, pointer to the obj_OutputLink.
  371.  
  372.     A double linked connection is created, an OIL_Connection
  373.     and an OOL_Connection structure.
  374.  
  375.   SEE ALSO
  376.     OBJ_RemoveConnection
  377.  
  378.  
  379. BeastLibrary/OBJ_DestroyObject
  380.  
  381.   NAME
  382.     OBJ_DestroyObject -- Destroy an object. (V1 Alpha)
  383.  
  384.   SYNOPSIS
  385.     OBJ_DestroyObject( Object, MethodFlags )
  386.                        A0      D3
  387.     struct BST_Object *OBJ_DestroyObject( struct BST_Object *, BST_MethodFlags );
  388.  
  389.   FUNCTION
  390.     This function combines a OBM_DISPOSE method with a OBJ_DisposeObject
  391.     call.
  392.  
  393.   INPUTS
  394.     Object      - Pointer to the object to be destroyed.
  395.     MethodFlags - MTHF_DOCHILDREN will be added by the function!!
  396.  
  397.   SEE ALSO
  398.     OBJ_DoMethod, OBJ_DisposeObject
  399.  
  400.  
  401. BeastLibrary/OBJ_DisposeObject
  402.  
  403.   NAME
  404.     OBJ_DisposeObject -- Dispose an object. (V1 Alpha)
  405.  
  406.   SYNOPSIS
  407.     OBJ_DisposeObject( Object )
  408.                        A0
  409.     void OBJ_DisposeObject( struct BST_Object * );
  410.  
  411.   FUNCTION
  412.     Dispose this object AND all it's children.
  413.  
  414.   INPUTS
  415.     Object - The object to be disposed. May be NULL.
  416.  
  417.   RESULT
  418.     This object AND the children objects are disposed.
  419.  
  420.   NOTES
  421.     This function will NOT perform an OBM_DISPOSE method.
  422.  
  423.   SEE ALSO
  424.     OBJ_NewObject, OBJ_DestroyObject
  425.  
  426.  
  427. BeastLibrary/OBJ_DoMethod
  428.  
  429.   NAME
  430.     OBJ_DoMethod -- Perform a method on a object. (V1 Alpha)
  431.  
  432.   SYNOPSIS
  433.     Result = OBJ_DoMethod( Object, Method_ID, TagList, MethodFlags )
  434.                            A0      D0         A1       D3
  435.     BST_MethodFlags OBJ_DoMethod( struct BST_Object *, BST_Method, struct TagItem *, BST_MethodFlags );
  436.  
  437.   FUNCTION
  438.     Trigger a method on a certain object.
  439.  
  440.   INPUTS
  441.     Object      - Pointer to the object (may NULL).
  442.     Method_ID   - Method ID number.
  443.     TagList     - Pointer to the TagList used by the Method routine.
  444.     MethodFlags - Special method flags;
  445.                           See the Beast:Docs/Beast_OO/Methods.doc
  446.  
  447.   RESULT
  448.     Result = The new method flags
  449.  
  450.                   Method call with the following registers set;
  451.                           D2 = Method_ID
  452.                           D3 = MethodFlags
  453.                           A2 = Object
  454.                           A3 = TagList
  455.  
  456.     As a result the method must deliver the new MethodFlags in d0.
  457.     Besides the discussed MethodFlags (INPUTS) there are some more;
  458.           See the Beast:Docs/Beast_OO/Methods.doc
  459.  
  460.   SEE ALSO
  461.     OBJ_MethodToParent, OBJ_MethodToChildren
  462.  
  463.  
  464. BeastLibrary/OBJ_FromInput
  465.  
  466.   NAME
  467.     OBJ_FromInput -- Trigger methods connections to an input. (V1 Alpha)
  468.  
  469.   SYNOPSIS
  470.     OBJ_FromInput( Object, InputMethod, MethodFlags, TagList )
  471.                    A0,     D0           D3           A1
  472.     BST_MethodFlags OBJ_FromInput( struct BST_Object *, BST_Method, BST_MethodFlags, struct TagItem * );
  473.  
  474.   FUNCTION
  475.     Request input from the method 'InputMethod', this will trigger ( if
  476.     connected ) a method at the object connected to the 'InputMethod'.
  477.  
  478.   INPUTS
  479.     Object       - Pointer to the object.
  480.     InputMethod  - The input method number.
  481.     MethodFlags  - The Method flags, see OBJ_DoMethod.
  482.     TagList      - The TagList put to the input/output-methods of the
  483.                    connection.
  484.  
  485.   SEE ALSO
  486.     OBJ_ToOutput, OBJ_CreateConnection
  487.  
  488.  
  489. BeastLibrary/OBJ_MethodToChildren
  490.  
  491.   NAME
  492.     OBJ_MethodToChildren -- Delegate the method to the children. (V1 Alpha)
  493.  
  494.   SYNOPSIS
  495.     Result = OBJ_MethodToChildren( Object, Method_ID, TagList, MethodFlags )
  496.                                    A0      D0         A1       D3
  497.  
  498.   FUNCTION
  499.     See DoMethod for full description. 
  500.     This function pass the method to the children. This is used in a method
  501.     definition when the MTHF_PASSTOCHILD flag is set.
  502.  
  503.   INPUTS
  504.     Object      - Pointer to the object (may NULL).
  505.     Method_ID   - Method ID number.
  506.     TagList     - Pointer to the TagList used by the Method routine.
  507.     MethodFlags - Special method flags;
  508.  
  509.   RESULT
  510.     Result = The new method flags
  511.  
  512.     Method call with the following registers set;
  513.  
  514.           D2 = Method_ID
  515.           D3 = MethodFlags
  516.           A2 = Object
  517.           A3 = TagList
  518.  
  519.     As a result the method must deliver the new MethodFlags in d0.
  520.  
  521.   NOTES
  522.  
  523.   SEE ALSO
  524.     OBJ_DoMethod
  525.  
  526.  
  527. BeastLibrary/OBJ_MethodToParent
  528.  
  529.   NAME
  530.     OBJ_MethodToParent -- Delegate the method to the parent. (V1 Alpha)
  531.  
  532.   SYNOPSIS
  533.     Result = OBJ_MethodToParent( Object, Method_ID, TagList, MethodFlags )
  534.                                  A0      D0         A1       D3
  535.     BST_MethodFlags OBJ_MethodToParent( struct BST_Object *, BST_Method, struct TagItem *, BST_MethodFlags );
  536.  
  537.   FUNCTION
  538.     See DoMethod for full description. 
  539.     This function pass the method to the parent. In this way the method won't
  540.     be triggered at the caller object. Remember to set the MTHF_DOPARENTS flags
  541.     the method should be delegated to other parents as well.
  542.  
  543.   INPUTS
  544.     Object      - Pointer to the object (may NULL).
  545.     Method_ID   - Method ID number.
  546.     TagList     - Pointer to the TagList used by the Method routine.
  547.     MethodFlags - Special method flags;
  548.  
  549.   RESULT
  550.     Result = The new method flags
  551.  
  552.     Method call with the following registers set;
  553.  
  554.           D2 = Method_ID
  555.           D3 = MethodFlags
  556.           A2 = Object
  557.           A3 = TagList
  558.  
  559.     As a result the method must deliver the new MethodFlags in d0.
  560.  
  561.   SEE ALSO
  562.     OBJ_DoMethod
  563.  
  564.  
  565. BeastLibrary/OBJ_NewObject
  566.  
  567.   NAME
  568.     OBJ_NewObject -- Create a new object. (V1 Alpha)
  569.  
  570.   SYNOPSIS
  571.     Result = OBJ_NewObject( Class, Class_ID, Parent )
  572.     D0                      A0     A1        D0
  573.     struct BST_Object *OBJ_NewObject( struct BST_Class *, char *, struct BST_Object * );
  574.  
  575.   FUNCTION
  576.     Create a new object. The object is added 'under' the Parent. In version
  577.     V1 Alpha multiple parents are not supported. If the Parent is null the
  578.     object is added under the Beast root, or when the Beast FileSystem is
  579.     available it's added under the UserClass.
  580.  
  581.   INPUTS
  582.     Class    - Pointer to an already known class (private class)
  583.                NULL if not used. (normally NULL).
  584.     Class_ID - Pointer to the name of the public class.
  585.     Parent   - Pointer to the parent object or NULL.
  586.  
  587.   RESULT
  588.     Result - Pointer to created object. NULL if the object could
  589.              not be added.
  590.  
  591.   SEE ALSO
  592.     OBJ_DisposeObject
  593.  
  594.  
  595. BeastLibrary/OBJ_RemoveConnection
  596.  
  597.   NAME
  598.     OBJ_RemoveConnection -- (V1 Alpha)
  599.  
  600.   SYNOPSIS
  601.     OBJ_RemoveConnection( OxL_Connection )
  602.                           A1
  603.     void OBJ_RemoveConnection( struct obj_OutputLink * );
  604.  
  605.   FUNCTION
  606.     Remove a created OIL_Connection or OOL_Connection.
  607.  
  608.   INPUTS
  609.     OxL_Connection - Pointer to an OIL/OOL_Connection.
  610.  
  611.   RESULT
  612.     The OIL_Connection and OOL_Connection structures are destroyed.
  613.  
  614.   SEE ALSO
  615.     OBJ_CreateConnection
  616.  
  617.  
  618. BeastLibrary/OBJ_ToOutput
  619.  
  620.   NAME
  621.     OBJ_ToOutput -- Trigger methods connections to an output. (V1 Alpha)
  622.  
  623.   SYNOPSIS
  624.     Result = OBJ_ToOutput( Object, TagList, OutputMethod, MethodFlags )
  625.                            A0      A1       D0            D3
  626.     BST_MethodFlags OBJ_ToOutput( struct BST_Object *, struct TagItem *, BST_Method, BST_MethodFlags );
  627.  
  628.   FUNCTION
  629.     'Output' the TagList (A1) to the connected input, the used output
  630.     is the OutputMethod (D0). The object is triggered which is connected
  631.     to 'Object' at MethodID 'OutputMethod'.
  632.  
  633.   INPUTS
  634.     Object       - Pointer to the object.
  635.     TagList      - The TagList put to the input/output-method of the
  636.                    connection.
  637.     OutputMethod - The output method ID.
  638.     MethodFlags  - The Method flags, see OBJ_DoMethod.
  639.  
  640.   RESULT
  641.     Result = The new methodflags.
  642.  
  643.   SEE ALSO
  644.     OBJ_FromInput, OBJ_CreateConnection, OBJ_DoMethod
  645.  
  646.  
  647.